Skip to content

Add docs for changing cluster plan between Standard and Basic #19462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Apr 3, 2025

Conversation

katmayb
Copy link
Contributor

@katmayb katmayb commented Mar 20, 2025

Fixes DOC-10627

This PR adds a page to describe changing cluster plans between Standard and Basic clusters.

Also:

  • Added a short section on the cluster management pages for Basic and Standard to direct customers to the new page.
  • Updated some errors here and there.

Preview

New page: https://deploy-preview-19462--cockroachdb-docs.netlify.app/docs/cockroachcloud/change-plan-between-basic-and-standard.html

@katmayb katmayb marked this pull request as draft March 20, 2025 19:52
Copy link

github-actions bot commented Mar 20, 2025

Files changed:

Copy link

netlify bot commented Mar 20, 2025

Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name Link
🔨 Latest commit 53a58dd
🔍 Latest deploy log https://app.netlify.com/sites/cockroachdb-interactivetutorials-docs/deploys/67eeee8c2787b10008124cb0

Copy link

netlify bot commented Mar 20, 2025

Deploy Preview for cockroachdb-api-docs canceled.

Name Link
🔨 Latest commit 53a58dd
🔍 Latest deploy log https://app.netlify.com/sites/cockroachdb-api-docs/deploys/67eeee8c05ffff0008038b2f

Copy link

netlify bot commented Mar 20, 2025

Netlify Preview

Name Link
🔨 Latest commit 53a58dd
🔍 Latest deploy log https://app.netlify.com/sites/cockroachdb-docs/deploys/67eeee8c87c9130008fe6aed
😎 Deploy Preview https://deploy-preview-19462--cockroachdb-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@katmayb katmayb force-pushed the cloud-change-plan-docs branch 2 times, most recently from 0e7f08c to 0f29ee4 Compare March 20, 2025 20:35
@katmayb katmayb requested a review from jaiayu March 20, 2025 20:42

To change your cluster's plan between {{ site.data.products.basic }} and {{ site.data.products.standard }}, refer to [Change a Cluster's Plan Between Standard and Basic]({% link cockroachcloud/change-plan-between-basic-and-standard.md %}).

To change from {{ site.data.products.basic }} to {{ site.data.products.advanced }}, you must first change your cluster's plan from {{ site.data.products.basic }} to {{ site.data.products.standard }}, and then you can refer to [Change a Cluster's Plan from Standard to Advanced]({% link cockroachcloud/change-plan-from-standard-to-advanced.md %}).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure this is required - I think you would be able to go straight from Basic to Advanced with these instructions. Can you check with @marksoper or @devarshishah3?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I picked this up from the linked google doc in the issue, I'll wait for confirmation on the recommendation here.


## Before you begin

You'll need the [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) role on the running {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster in order to change the cluster's [plan]({% link cockroachcloud/index.md %}#plans).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@katmayb Cluster Operator roles can also perform the plan change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done!

1. On the [**Cluster Overview** page]({% link cockroachcloud/cluster-overview-page.md %}), select the **Action** dropdown in the top-right corner, and then **Change plan type**.
1. Choose a [plan]({% link cockroachcloud/index.md %}#plans) from {{ site.data.products.standard }} or {{ site.data.products.basic }} to change to. The current plan of the cluster will be highlighted. Select **Next: Capacity**.
1. For capacity:
- If you are changing to a {{ site.data.products.standard }} plan, choose the amount of [provisioned capacity]({% link cockroachcloud/plan-your-cluster.md %}#provisioned-capacity) you want for your cluster. Select **Next: Finalize**.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@katmayb we give a recommendation in CC console for your provisioned vCPU depending on your peak RU/s in the last 30 days. For your reference, we calculate this vCPU based on the 30-day peak RU/s plus a 40% buffer, then convert using 500 RU/s = 1 vCPU. We use a 10-minute roll-up for the peak RU/s. -- This calculation may be good to include in docs somewhere to reference; Mike had suggested adding it to "Plan your cluster".

There are also a few caveats that we may want to mention with respect to the recommendation in the UI:

  • This should be interpreted as a suggestion. Users should keep an eye on their CPU utilization % and adjust their compute capacity as needed.
  • Standard currently supports a maximum of 60 vCPUs. If we estimate you need more than 60 vCPU, we tell them that we estimate they need more than our capacity, but "You can provision up to 60 vCPU. If your workload consistently spikes above that level you may experience performance issues."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a section to "plan your cluster" with the calculation. And I've added that the Cloud Console provides a suggestion but that users should monitor this.

Your last bullet point — I've added to the Plan your cluster page. I haven't not specifically mentioned the 60 vCPUs for ease of keeping the docs up to date. But, if that's a number that won't change frequently or you'd prefer it specified I can update these changes.

1. For capacity:
- If you are changing to a {{ site.data.products.standard }} plan, choose the amount of [provisioned capacity]({% link cockroachcloud/plan-your-cluster.md %}#provisioned-capacity) you want for your cluster. Select **Next: Finalize**.
- If you are changing to a [{{ site.data.products.basic }} plan]({% link cockroachcloud/create-a-basic-cluster.md %}#step-4-configure-cluster-capacity), choose whether the cluster should have **Unlimited** capacity to scale, or **Set a monthly limit**. Select **Next: Finalize**.
1. Review the changes and then **Update cluster**.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We include the following in the UI, if it makes sense to include here as well:

  • The upgrade process will take up to 5 mins
  • Their cluster will remain functional under the current plan during the switching period
  • They can switch back the plan if needed. But when you go from Standard to Basic, you need to wait 48 hours before being able to change the plan back to Standard.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 48 hours wait is just for if the cluster was originally Standard? I have a note earlier on the page that mentions this generally about any switch back, so maybe I need to change that?

I have added these as bullet points to the final step.


These instructions assume you already have the following:

- A [CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster]({% link cockroachcloud/quickstart.md %}) from which you want to migrate data.
- A [CockroachDB {{ site.data.products.standard }} cluster]({% link cockroachcloud/quickstart.md %}) of which you want to change the plan.
- A [paid CockroachDB {{ site.data.products.advanced }} cluster]({% link cockroachcloud/quickstart-trial-cluster.md %}). Your first paid CockroachDB {{ site.data.products.advanced }} cluster is free for a 30-day trial.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 21 - the part about your first cluster being free for 30 days is actually no longer true. We have replaced this version of the free trial now.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed

Copy link

@jaiayu jaiayu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @katmayb. I left a few comments inline. There are a couple of additional considerations that should be called out for the UI workflow:

  • If the cluster was created on legacy architecture, then it cannot be upgraded via UI. The cluster will not support multi-region features or private connections. To use these features, a customer would need to do backup and restore into a new cluster. If they still want to change the plan for their current cluster despite the feature limitations, they can do so via API (https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api#change-a-clusters-plan).
  • If a cluster was recently downgraded to Basic from Standard, it must wait 48 hours to be upgraded back to Standard.
  • When you're downgrading from Standard to Basic, you need to disable Standard-only premium features first (private connections, manual version control setting, metrics/log export to DataDog/Prometheus).

I also spoke to Devarshi about changes to the "Migrate from Standard/Basic to Advanced" page. He said we should keep using the terminology "Migrate" in that case since we don't support simple plan changes for that flow yet. The user would still need to perform a full migration.

@katmayb
Copy link
Contributor Author

katmayb commented Mar 21, 2025

Thanks @katmayb. I left a few comments inline. There are a couple of additional considerations that should be called out for the UI workflow:

  • If the cluster was created on legacy architecture, then it cannot be upgraded via UI. The cluster will not support multi-region features or private connections. To use these features, a customer would need to do backup and restore into a new cluster. If they still want to change the plan for their current cluster despite the feature limitations, they can do so via API (https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api#change-a-clusters-plan).
  • If a cluster was recently downgraded to Basic from Standard, it must wait 48 hours to be upgraded back to Standard.
  • When you're downgrading from Standard to Basic, you need to disable Standard-only premium features first (private connections, manual version control setting, metrics/log export to DataDog/Prometheus).

I also spoke to Devarshi about changes to the "Migrate from Standard/Basic to Advanced" page. He said we should keep using the terminology "Migrate" in that case since we don't support simple plan changes for that flow yet. The user would still need to perform a full migration.

I have mentioned these in the "Considerations" and prerequisites. Regarding "legacy architecture", what do we mean here exactly — and is that how we want to phrase it in docs?

@katmayb katmayb requested a review from jaiayu March 21, 2025 13:17

To change your cluster's plan between {{ site.data.products.basic }} and {{ site.data.products.standard }}, refer to [Change a Cluster's Plan Between Standard and Basic]({% link cockroachcloud/change-plan-between-basic-and-standard.md %}).

To change from {{ site.data.products.basic }} to {{ site.data.products.advanced }}, you must first change your cluster's plan from {{ site.data.products.basic }} to {{ site.data.products.standard }}, and then you can refer to [Change a Cluster's Plan from Standard to Advanced]({% link cockroachcloud/migrate-from-standard-to-advanced.md %}).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@katmayb can we remove "you must first change your cluster's plan from" -- I think they can use the Standard <> Advanced instructions to directly migrate from Basic to Advanced.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, sorry! Updated.

## Change a cluster's plan

{{site.data.alerts.callout_info}}
After changing your cluster's plan, you will not be able to change the plan again for 48 hours.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only true for Standard to Basic, like you have it called out under considerations

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have updated this to include the Standard to Basic callout.

@katmayb katmayb marked this pull request as ready for review March 25, 2025 17:59
@katmayb katmayb requested a review from jaiayu March 25, 2025 18:06
@@ -43,6 +43,10 @@ You can decrease the provisioned capacity only three times within a 7-day period

The CockroachDB {{ site.data.products.cloud }} Console provides insight into your cluster's compute usage relative to its provisioned capacity on a monthly basis. We recommend that you maintain at minimum a 40% capacity buffer over time, and that you increase this buffer if the workload is unpredictable or highly sensitive to query latency. You now have the advantage of historical data about the cluster's performance to help you maintain and improve the cluster's performance over time.

### Changing cluster plan provisioned capacity recommendations

If you change your cluster's plan from {{ site.data.products.basic }} to {{ site.data.products.standard }}, the Cloud Console will provide a suggested provisioned capacity. This is calculated depending on your [peak request units (RUs)]({% link cockroachcloud/plan-your-cluster-basic.md %}) in the last 30 days on the {{ site.data.products.basic }} cluster plan. The vCPU suggestion is based on the 30-day peak RUs with an additional 40% buffer. 500 RUs can be converted to 1 vCPU. If the estimate is beyond the {{ site.data.products.standard }} plan's maximum supported vCPU, you may experience performance issues if your cluster's workload consistently spikes above that level.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. Two comments:

  • The unit we look at is peak RU per second. So anywhere we are referencing RUs -- that should be RU/sec.
  • The last thing we might want to include is the roll-up period we use for the peak RU/sec. We use a 10-minute roll up period.


To change your cluster's plan between {{ site.data.products.basic }} and {{ site.data.products.standard }}, refer to [Change a Cluster's Plan Between Standard and Basic]({% link cockroachcloud/change-plan-between-basic-and-standard.md %}).

To change from {{ site.data.products.basic }} to {{ site.data.products.advanced }}, refer to [Change a Cluster's Plan from Standard or Basic to Advanced]({% link cockroachcloud/migrate-from-standard-to-advanced.md %}).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the title needs to be updated here - still says "Change a cluster's plan" instead of "Migrate..."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


To change your cluster's plan between {{ site.data.products.basic }} and {{ site.data.products.standard }}, refer to [Change a Cluster's Plan Between Standard and Basic]({% link cockroachcloud/change-plan-between-basic-and-standard.md %}).

To change from {{ site.data.products.standard }} to {{ site.data.products.advanced }}, refer to [Change a Cluster's Plan from Standard to Advanced]({% link cockroachcloud/migrate-from-standard-to-advanced.md %}).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above. The title of the page might need to be updated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

Copy link

@jaiayu jaiayu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also update cloud release notes @katmayb! Thank you!

@katmayb katmayb requested a review from jaiayu March 26, 2025 15:38
@katmayb
Copy link
Contributor Author

katmayb commented Mar 26, 2025

Can we also update cloud release notes @katmayb! Thank you!

@jaiayu I've added a very simple cloud release note. I added yesterday's date, not sure when the release date is. Please let me know! Changed the instances of RUs to RU/sec (we may need to do a follow-up to check this across the docs, I noticed inconsistency here).

@katmayb katmayb requested a review from florence-crl April 3, 2025 17:21
Copy link
Contributor

@florence-crl florence-crl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm pending suggestions.


### Considerations

- If the cluster was created on legacy architecture, then it cannot be upgraded in the Cloud Console. The cluster will not support multi-region features or private connections. To use these features, you must take a [backup]({% link cockroachcloud/backup-and-restore-overview.md %}) and restore into a new cluster. To change the plan for your current cluster despite the feature limitations, you can use the [Cloud API]({% link cockroachcloud/cloud-api.md %}#change-a-clusters-plan).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the cluster was created on legacy architecture

How does user know if their cluster was created on legacy architecture?

@@ -43,6 +43,10 @@ You can decrease the provisioned capacity only three times within a 7-day period

The CockroachDB {{ site.data.products.cloud }} Console provides insight into your cluster's compute usage relative to its provisioned capacity on a monthly basis. We recommend that you maintain at minimum a 40% capacity buffer over time, and that you increase this buffer if the workload is unpredictable or highly sensitive to query latency. You now have the advantage of historical data about the cluster's performance to help you maintain and improve the cluster's performance over time.

### Changing cluster plan provisioned capacity recommendations
Copy link
Contributor

@florence-crl florence-crl Apr 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one last suggestion, would you be able to change this heading to: "Recommended provisioned capacity when changing cluster plan"?

Copy link
Contributor

@mikeCRL mikeCRL left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made two suggestions based on the feedback/question from @florence-crl. Thanks.

{{site.data.alerts.end}}

1. On the [**Clusters** page]({% link cockroachcloud/cluster-management.md %}#view-clusters-page), select the cluster that requires a plan change.
1. On the [**Cluster Overview** page]({% link cockroachcloud/cluster-overview-page.md %}), select the **Action** dropdown in the top-right corner, and then **Change plan type**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this option is unavailable, refer to Considerations.

@katmayb katmayb force-pushed the cloud-change-plan-docs branch from 568742c to 53a58dd Compare April 3, 2025 20:24
@katmayb katmayb merged commit 5412b39 into main Apr 3, 2025
6 checks passed
@katmayb katmayb deleted the cloud-change-plan-docs branch April 3, 2025 20:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants